=begin pod

=TITLE class Set

=SUBTITLE Immutable collection of distinct objects

    class Set does Setty { }

A C<Set> is an immutable set, meaning a collection of distinct elements in no
particular order. (For I<mutable> sets, see L<SetHash> instead.)

Objects/values of any type are allowed as set elements. Within a C<Set>, every
element is guaranteed to be unique (in the sense that no two elements would
compare positively with the L<===> operator):

=begin code
my $fruits = set <peach apple orange apple apple>;

say $fruits.elems;      # OUTPUT: «3␤»
say $fruits.keys.sort;  # OUTPUT: «apple orange peach␤»
=end code

C<Set>s can be treated as object hashes using the C<{ }> postcircumfix operator,
which returns the value C<True> for keys that are elements of the set, and
C<False> for keys that aren't:

    my $fruits = set <peach apple orange apple apple>;
    say $fruits<apple>;  # OUTPUT: «True␤»
    say $fruits<kiwi>;   # OUTPUT: «False␤»

=head1 Creating C<Set> objects

C<Set>s can be composed using the L<set|#sub set> subroutine (or C<Set.new>, for
which it is a shorthand). Any positional parameters, regardless of their type,
become elements of the set:

    my $n = set "zero" => 0, "one" => 1, "two" => 2;
    say $n.keys.perl;        # OUTPUT: «(:two(2), :zero(0), :one(1)).Seq␤»
    say $n.keys.map(&WHAT);  # OUTPUT: «((Pair) (Pair) (Pair))␤»

Alternatively, the C<.Set> coercer (or its functional form, C<Set()>) can be
called on an existing object to coerce it to a C<Set>. Its semantics depend on
the type and contents of the object. In general it evaluates the object in list
context and creates a set with the resulting items as elements, although for
Hash-like objects or Pair items, only the keys become elements of the set - and
keys mapped to values which boolify to C<False> are skipped:

    my $n = ("zero" => 0, "one" => 1, "two" => 2).Set;
    say $n.keys.perl;        # OUTPUT: «("one", "two").Seq␤»
    say $n.keys.map(&WHAT);  # OUTPUT: «((Str) (Str))␤»

Furthermore, you can get a C<Set> by using set operators (see next section) on
objects of other types such as L<List>, which will internally call C<.Set>
on them before performing the operation. Be aware of the tight precedence of
those operators though, which may require you to use parentheses around arguments:

    say (1..5) (^) 4;  # OUTPUT: «set(1, 2, 3, 5)␤»

=head1 Operators

Perl 6 provides common set operators, which can take C<Set>s (or any other
collections) as input, and return result sets as new C<Set> objects. For
example:

=begin code
my ($a, $b) = set(1, 2, 3), set(2, 4);

say $a (<) $b;  # OUTPUT: «False␤»
say $a (&) $b;  # OUTPUT: «set(2)␤»
say $a (^) $b;  # OUTPUT: «set(1, 3, 4)␤»

# Unicode versions:
say $a ⊂ $b;  # OUTPUT: «False␤»
say $a ∩ $b;  # OUTPUT: «set(2)␤»
say $a ⊖ $b;  # OUTPUT: «set(1, 3, 4)␤»
=end code

See L<Set/Bag Operators|/language/setbagmix#Set/Bag_Operators> for a complete
list of set operators with detailed explanations.

=head1 Subroutines

=head2 sub set

    sub set(*@args --> Set)

Creates a C<Set> from the given C<@args>

=head1 See Also

L<Sets, Bags, and Mixes|/language/setbagmix>

=end pod

# vim: expandtab softtabstop=4 shiftwidth=4 ft=perl6
